---
title: SchemaBuilder
menu: API
description: API docs for Pothos SchemaBuilder
---

SchemaBuilder is the core class of Pothos. It can be used to build types, and merge them into a
graphql.js Schema.

## `constructor<SchemaTypes>(options)`

- typeParam: `SchemaTypes`: A type that describes the backing models for your schema
- options: `SchemaBuilderOptions`

### `SchemaTypes`

```typescript
type SchemaTypes {
  // Shape of the context arg in your resolvers
  Context?: object;
  // A map of Object type names to their backing models.
  Objects?: object;
  // A map of Input type names to their backing models.
  Inputs?: object;
  // A map of Interface type names to their backing models.
  Interfaces?: object;
  // Map of scalar names to Input and Output shapes.  Can be used to overwrite default scalar types,
  // or to add type information for custom scalars
  Scalars?: {
    [s: string]: {
      Input: unknown;
      Output: unknown;
    };
  };
  // When set to false, fields will be NonNullable by default (requires corresponding change in builder options)
  DefaultFieldNullability?: false;
  // When provided, input fields and arguments will be required by default (requires corresponding change in builder options)
  DefaultInputFieldRequiredness?: true;
}
```

### SchemaBuilderOptions

```typescript
type SchemaBuilderOptions = {};
```

By default there are no options for SchemaBuilder, but plugins may contribute additional options

## `queryType(options, fields?)`

creates the `Query` with a set of Query fields

- `options`: `QueryTypeOptions`
- `fields?`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

### QueryTypeOptions

```typescript
type QueryTypeOptions = {
  description?: string;
  fields: FieldsFunction;
};
```

- `description`: A description of the current type
- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `queryFields(fields)`

add a set of fields to the `Query` type.

- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `queryField(name, field)`

add a single field to the `Query` type.

- `name`: the name of the field
- `field`: a function that receives a [`FieldBuilder`](./field-builder), and returns field ref. See
  [`FieldBuilder`](./field-builder) for more details.

## `mutationType(options, fields?)`

creates the `Mutation` with a set of Mutation fields

- `options`: `MutationTypeOptions`
- `fields?`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

### MutationTypeOptions

```typescript
type MutationTypeOptions = {
  description?: string;
  fields: FieldsFunction;
};
```

- `description`: A description of the current type
- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `mutationFields(fields)`

add a set of fields to the `Mutation` type.

- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `mutationField(name, field)`

add a single field to the `Mutation` type.

- `name`: the name of the field
- `field`: a function that receives a [`FieldBuilder`](./field-builder), and returns field ref. See
  [`FieldBuilder`](./field-builder) for more details.

## `subscriptionType(options, fields?)`

creates the `Subscription` with a set of Subscription fields

- `options`: `SubscriptionTypeOptions`
- `fields?`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

### SubscriptionTypeOptions

```typescript
type SubscriptionTypeOptions = {
  description?: string;
  fields: FieldsFunction;
};
```

- `description`: A description of the current type
- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `subscriptionFields(fields)`

add a set of fields to the `Subscription` type.

- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `subscriptionField(name, field)`

add a single field to the `Subscription` type.

- `name`: the name of the field
- `field`: a function that receives a [`FieldBuilder`](./field-builder), and returns field ref. See
  [`FieldBuilder`](./field-builder) for more details.

## `objectType(param, options, fields?)`

- `param`: A key of the `Objects` property in `SchemaTypes`, a class, or a TypeRef created by
  `builder.objectRef`

- `options`: `ObjectTypeOptions`
- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

### `ObjectTypeOptions`

```typescript
type ObjectTypeOptions = {
  description?: string;
  fields: FieldsFunction;
  interfaces?: Interfaces;
  isTypeOf: (obj: InterfaceShape) => boolean;
  name?: string;
};
```

- `description`: A description of the current type
- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

- `isTypeOf`: Recomended when implementing interfaces. This is a method that will be used when
  determining if a value of an implemented interface is of the current type.

- `interfaces`: an array of interfaces implemented by this interface type. Items in this array
  should be an interface param. See `param` argument of `interfaceType`

- `name`: name of GraphQL type. Required when param is a class

## `objectFields(param, fields)`

add a set of fields to the object type.

- `param`: A key of the `Objects` property in `SchemaTypes`, a class, or a TypeRef created by
  `builder.objectRef`

- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `objectField(param, name, field)`

add a single field to the object type.

- `name`: the name of the field
- `param`: A key of the `Objects` property in `SchemaTypes`, a class, or a TypeRef created by
  `builder.objectRef`

- `field`: a function that receives a [`FieldBuilder`](./field-builder), and returns field ref. See
  [`FieldBuilder`](./field-builder) for more details.

## `objectRef<T>(name)`

Creates a Ref object represent an object that has not been implemented. This can be useful for
building certain types of plugins, or when building a modular schema where you don't want to define
all types in SchemaTypes, or import the actual implementation of each object type you use.

- `name`: string, name of the type that this ref represents. Can be overwritten when implemented.
- `T`: a type param to define the backing shape for the type that this ref represents

## `interfaceType(param, options, fields?)`

- `param`: A key of the `Interfaces` property in `SchemaTypes`, a class, or a TypeRef created by
  `builder.interfaceRef`

- `options`: `InterfaceTypeOptions`
- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

### `InterfaceTypeOptions`

```typescript
type InterfaceTypeOptions = {
  description?: string;
  fields: FieldsFunction;
  interfaces?: Interfaces;
  name?: string;
};
```

- `description`: A description of the current type
- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

- `interfaces`: an array of interfaces implemented by this interface type. Items in this array
  should be an interface param. See `param` argument of `interfaceType`

- `name`: name of GraphQL type. Required when param is a class

## `interfaceFields(param, fields)`

add a set of fields to the interface type.

- `param`: A key of the `Interfaces` property in `SchemaTypes`, a class, or a TypeRef created by
  `builder.interfaceRef`

- `fields`: a function that receives a [`FieldBuilder`](./field-builder), and returns an object of
  field names to field refs. See [`FieldBuilder`](./field-builder) for more details.

## `interfaceField(paran, name, field)`

add a single field to the interface type.

- `param`: A key of the `Interfaces` property in `SchemaTypes`, a class, or a TypeRef created by
  `builder.interfaceRef`

- `name`: the name of the field
- `field`: a function that receives a [`FieldBuilder`](./field-builder), and returns field ref. See
  [`FieldBuilder`](./field-builder) for more details.

## `interfaceRef<T>(name)`

Creates a Ref object represent an interface that has not been implemented. This can be useful for
building certain types of plugins, or when building a modular schema where you don't want to define
all types in SchemaTypes, or import the actual implementation of each interface type you use.

- `name`: string, name of the type that this ref represents. Can be overwritten when implemented.
- `T`: a type param to define the backing shape for the type that this ref represents

## `unionType(name, options)`

- `name`: A string
- `options`: `UnionTypeOptions`

### `UnionTypeOptions`

```typescript
type UnionTypeOptions = {
  description?: string;
  types: Member[] | (() => Member[]);
  resolveType: (parent: UnionShape, context) => MaybePromise<GraphQLObjectType | TypeName>;
};
```

- `description`: A description of the current type
- `types`: an array of object types included in the union type. Items in this array should be Object
  params. See `param` argument in `builder.objectType`.

- `resolveType`: A function called when resolving the type of a union value. `parent` will be a
  union of the backing models of the types provided in `types`. This function should return the name
  of one of the union member types.

## `enumType(param, options)`

- `param`: A string name of the enum or a typescript enum
- `options`: `EnumTypeOptions`

### `EnumTypeOptions`

```typescript
type UnionTypeOptions = {
  description?: string;
  values?: Values;
  name?: string;
};
```

- `description`: A description of the current type
- `values`: can be either an array of strings \(you may need to use `as const` to get proper type
  names\) or a `GraphQLEnumValueConfigMap`. values is only required when param is not an enum

- `name`: required when param is an enum

## `addScalarType(name, scalar, options)`

- `name`: A key of the `Interface` property in `SchemaTypes`
- `scalar`: A `GraphQLScalar`

## `scalarType(name, options)`

- `name`: A key of the `Interface` property in `SchemaTypes`
- `options`: `ScalarTypeOptions`

### ScalarTypeOptions

```typescript
description?: string;
// Serializes an internal value to include in a response.
serialize: GraphQLScalarSerializer<OutputShape>;
// Parses an externally provided value to use as an input.
parseValue?: GraphQLScalarValueParser<InputShape>;
// Parses an externally provided literal value to use as an input.
parseLiteral?: GraphQLScalarLiteralParser<InputShape>;
extensions?: Readonly<Record<string, unknown>>;
```

## `inputType(param, options)`

- `param`: a string or InputRef created by `builder.inputRef`
- `options`: `InputTypeOptions`

### `InputTypeOptions`

```typescript
type InputTypeOptions = {
  description?: string;
  fields: InputShape;
};
```

- `description`: A description of the current type
- `fields`: a function that receives an `InputFieldBuilder`, and returns an object of field names to
  field definitions. See [`InputFieldBuilder`](./input-field-builder) for more details. If `name` is
  a key of the `Input` property in `SchemaTypes`, shape will show type errors for any fields that do
  not match the types provided in `SchemaTypes`.

## `inputRef<T>(name)`

Creates a Ref object represent an input object that has not been implemented. This can be useful for
defining recursive input types, for building certain types of plugins, or when building a modular
schema where you don't want to define all types in SchemaTypes, or import the actual implementation
of each input type you use.

- `name`: string, name of the type that this ref represents. Can be overwritten when implemented.
- `T`: a type param to define the backing shape for the type that this ref represents

## `args(fields)`

Creates an arguments object which can be used as the `args` option in a field definition.

- `fields`: a function that receives an [`ArgBuilder`](./arg-builder), and returns an object of
  field names to field definitions. See [`ArgBuilder`](./arg-builder) for more details.

## `toSchema(types)`

Takes an array of types created by [`SchemaBuilder`](./schema-builder#schemabuilder) and returns a
[`GraphQLSchema`](https://graphql.org/graphql-js/type/#graphqlschema)

## `SchemaBuilder.allowPluginReRegistration`

`SchemaBuilder.allowPluginReRegistration` is a static `boolean` on the SchemaBuilder class that can
be set to allow plugins to call registerPlugin multiple times. This is useful for hot-module
reloading, but is `false` by default to catch any issues with duplicate versions of a plugin.
